org.globalplatform.contactless
Class GPCLSystem

java.lang.Object
  org.globalplatform.contactless.GPCLSystem

public class GPCLSystem
extends java.lang.Object

This class exposes a subset of the behavior of the CRS (OPEN extension) to other on-card components.

Since:

• export file version 1.0: initial version.
• export file version 1.2: new constants and methods added to help supporting non-UICC secure elements.

Field Summary

static short	AFI_ANY Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for all Contactless applications that belong to any family
static short	AFI_DATA_STORAGE Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Data Storage family
static short	AFI_FINANCIAL Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Financial family
static short	AFI_GAMING Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Gaming family
static short	AFI_IDENTIFICATION Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Identification family
static short	AFI_MEDICAL Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Medical family
static short	AFI_MULTIMEDIA Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Multimedia family
static short	AFI_TELECOMMUNICATION Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Telecommunication family
static short	AFI_TRANSPORT Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Transport family
static short	CARD_INFO_COUNTER_UPDATE The global CRS update counter.
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A The requested information is the CURRENT_PROTOCOL_DATA_TYPE_A (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '86').
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B The requested information is the CURRENT_PROTOCOL_DATA_TYPE_B (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '87').
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F The requested information is the CURRENT_PROTOCOL_DATA_TYPE_F (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '88').
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_A (i.e. content of INSTALL system parameter Tag '86' when sent to update OPEN parameters).
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_B (i.e. content of INSTALL system parameter Tag '87' when sent to update OPEN parameters).
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_F (i.e. content of INSTALL system parameter Tag '88' when sent to update OPEN parameters).
static byte	GPCL_CL_APPLICATION The OPEN uses this identifier to retrieve the CLApplet interface implemented by an applet.
static byte	GPCL_CL_APPLICATION_ACTIVATION_POLICY The OPEN uses this identifier to retrieve the CLAppletActivationPolicy interface implemented by an applet.
static byte	GPCL_CREL_APPLICATION The OPEN uses this identifier to retrieve the CRELApplication interface implemented by an applet.
static byte	GPCL_CRS_APPLICATION The OPEN uses this identifier to retrieve the CRSApplication interface implemented by an applet.
static short	GPCL_INTERFACE_ISO14443 Deprecated. Replaced by GPCL_PROXIMITY_IO_INTERFACE.
static short	GPCL_PROXIMITY_IO_INTERFACE This constant is used with setCommunicationInterface(short, boolean) to manage the availability of the proximity based communication interface.
static short	HOST_DEVICE_UI_AVAILABLE Bit mask meaning that the host device UI is currently available.
static short	HOST_DEVICE_UI_STATE_UNKNOWN Bit mask meaning that implementation is not able to provide any information about the state of the host device UI.
static byte	SECURE_ELEMENT_EMBEDDED The Secure Element is of type Embedded Secure Element.
static byte	SECURE_ELEMENT_SDCARD The Secure Element is of type Smart SD or Smart Micro SD Card.
static byte	SECURE_ELEMENT_UICC The Secure Element is of type UICC.
static byte	SECURE_ELEMENT_UNKNOWN The Secure Element type is of unknown type.

Method Summary

static boolean	checkCommunicationInterfaceAccess(GPRegistryEntry entry, short sInterface) Checks whether a GPRegistryEntry can be accessed through specified communication interface.
static short	getCardCLInfo(byte[] buffer, short offset, short info) Retrieve the OPEN's conctactless parameters.
static GPCLRegistryEntry	getGPCLRegistryEntry(javacard.framework.AID oAID) Gets a reference to a GPCLRegistryEntry interface.
static short	getHostDeviceUserInterfaceState() Gets the current state of the host device user interface (UI).
static GPCLRegistryEntry	getNextGPCLRegistryEntry(GPCLRegistryEntry oEntry, short sFamily) Iterates over contactless applets belonging to a particular Application Family.
static byte	getSecureElementType() Gets the type of the Secure Element.
static void	launchHostDeviceApplication(byte[] parameters, short offset, short length) Notifies the host device that it shall launch an application (on the host device) that is associated with the applet instance invoking this method.
static void	setCommunicationInterface(short sInterface, boolean onOff) Switches ON or OFF persistently the specified communication interface at GlobalPlatform card level.
static void	setVolatilePriority(GPCLRegistryEntry oEntry) Sets up or resets the volatile priority for the specified entry.

Methods inherited from class java.lang.Object

equals

Field Detail

GPCL_CL_APPLICATION

public static final byte GPCL_CL_APPLICATION

The OPEN uses this identifier to retrieve the CLApplet interface implemented by an applet.

See Also:

Constant Field Values

GPCL_CRS_APPLICATION

public static final byte GPCL_CRS_APPLICATION

The OPEN uses this identifier to retrieve the CRSApplication interface implemented by an applet.

See Also:

Constant Field Values

GPCL_CREL_APPLICATION

public static final byte GPCL_CREL_APPLICATION

The OPEN uses this identifier to retrieve the CRELApplication interface implemented by an applet.

See Also:

Constant Field Values

GPCL_CL_APPLICATION_ACTIVATION_POLICY

public static final byte GPCL_CL_APPLICATION_ACTIVATION_POLICY

The OPEN uses this identifier to retrieve the CLAppletActivationPolicy interface implemented by an applet.

Since:

export file version 1.2

See Also:

Constant Field Values

AFI_ANY

public static final short AFI_ANY

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for all Contactless applications that belong to any family

See Also:

Constant Field Values

AFI_TRANSPORT

public static final short AFI_TRANSPORT

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Transport family

See Also:

Constant Field Values

AFI_FINANCIAL

public static final short AFI_FINANCIAL

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Financial family

See Also:

Constant Field Values

AFI_IDENTIFICATION

public static final short AFI_IDENTIFICATION

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Identification family

See Also:

Constant Field Values

AFI_TELECOMMUNICATION

public static final short AFI_TELECOMMUNICATION

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Telecommunication family

See Also:

Constant Field Values

AFI_MEDICAL

public static final short AFI_MEDICAL

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Medical family

See Also:

Constant Field Values

AFI_MULTIMEDIA

public static final short AFI_MULTIMEDIA

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Multimedia family

See Also:

Constant Field Values

AFI_GAMING

public static final short AFI_GAMING

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Gaming family

See Also:

Constant Field Values

AFI_DATA_STORAGE

public static final short AFI_DATA_STORAGE

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Data Storage family

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_A (i.e. content of INSTALL system parameter Tag '86' when sent to update OPEN parameters).

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_B (i.e. content of INSTALL system parameter Tag '87' when sent to update OPEN parameters).

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_F (i.e. content of INSTALL system parameter Tag '88' when sent to update OPEN parameters).

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_A (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '86').

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_B (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '87').

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_F (i.e. encoded as the content of sub tag 'A0' of INSTALL system parameter Tag '88').

See Also:

Constant Field Values

CARD_INFO_COUNTER_UPDATE

public static final short CARD_INFO_COUNTER_UPDATE

The global CRS update counter. Each time a GPCLRegistryEntry information is updated, this counter is incremented. Used to indicate off-card applications the need for synchronization.

See Also:

Constant Field Values

GPCL_INTERFACE_ISO14443

public static final short GPCL_INTERFACE_ISO14443

Deprecated. Replaced by GPCL_PROXIMITY_IO_INTERFACE.

This constant is used with setCommunicationInterface(short, boolean) to manage a ISO14443 based communication interface.

See Also:

Constant Field Values

GPCL_PROXIMITY_IO_INTERFACE

public static final short GPCL_PROXIMITY_IO_INTERFACE

This constant is used with setCommunicationInterface(short, boolean) to manage the availability of the proximity based communication interface.

Since:

export file version 1.2

See Also:

Constant Field Values

SECURE_ELEMENT_UNKNOWN

public static final byte SECURE_ELEMENT_UNKNOWN

The Secure Element type is of unknown type.

Since:

export file 1.2

See Also:

Constant Field Values

SECURE_ELEMENT_UICC

public static final byte SECURE_ELEMENT_UICC

The Secure Element is of type UICC.

Since:

export file 1.2

See Also:

Constant Field Values

SECURE_ELEMENT_EMBEDDED

public static final byte SECURE_ELEMENT_EMBEDDED

The Secure Element is of type Embedded Secure Element.

Since:

export file 1.2

See Also:

Constant Field Values

SECURE_ELEMENT_SDCARD

public static final byte SECURE_ELEMENT_SDCARD

The Secure Element is of type Smart SD or Smart Micro SD Card.

Since:

export file 1.2

See Also:

Constant Field Values

HOST_DEVICE_UI_STATE_UNKNOWN

public static final short HOST_DEVICE_UI_STATE_UNKNOWN

Bit mask meaning that implementation is not able to provide any information about the state of the host device UI. If this bit mask is set, the state of the UI is unknown and all other bits shall be ignored.

Since:

export file 1.2

See Also:

getHostDeviceUserInterfaceState(), Constant Field Values

HOST_DEVICE_UI_AVAILABLE

public static final short HOST_DEVICE_UI_AVAILABLE

Bit mask meaning that the host device UI is currently available. If this bit mask is set, the UI shall be considered available, otherwise it shall be considered unavailable.

Since:

export file 1.2

See Also:

getHostDeviceUserInterfaceState(), Constant Field Values

Method Detail

getGPCLRegistryEntry

public static GPCLRegistryEntry getGPCLRegistryEntry(javacard.framework.AID oAID)

Gets a reference to a GPCLRegistryEntry interface.

Parameters:

oAID - AID of the applet whose GPCLRegistryEntry instance, if available, shall be retrieved. If null, the GPCLRegistryEntry instance corresponding of the applet invoking this method, if available, is returned.

Returns:

the GPCLRegistryEntry interface object, or null

• if there is no applet with the specified AID or,
• if the caller
  • has not GLOBAL REGISTRY privilege, and
  • has not CONTACTLESS ACTIVATION privilege, and
  • is not the Security Domain directly associated with the applet being investigated, and
  • is not the investigated applet itself, and
  • is a not CREL Application registered in the investigated applet's CREL list

getNextGPCLRegistryEntry

public static GPCLRegistryEntry getNextGPCLRegistryEntry(GPCLRegistryEntry oEntry,
                                                         short sFamily)

Iterates over contactless applets belonging to a particular Application Family.

Contactless applets are those applets that have access to the contactless interface (GPCL_INTERFACE_ISO14443), as specified by Communication Interface Access Parameters (see INSTALL system parameter Tag 'A5' or, if not present, implementation-dependent default OPEN values). This method returns the GPCLRegistryEntry object for the next contactless applet that matches the search criteria. This method shall only return entries corresponding to applets currently having access to the contactless interface.

• Application with GLOBAL REGISTRY privilege can iterate over all contactless Applications.
• Application with CONTACTLESS ACTIVATION privilege can iterate over all contactless Applications.
• A CREL Application can only iterate over its referencing contactless Applications.
• Security Domain can only iterate on its directly or indirectly associated contactless Application(s) unless it has the GLOBAL REGISTRY privilege.

Parameters:

oEntry -

• if oEntry is null, this method returns the first Entry matching the specified family.
• If the list is empty, the method shall return null.
• If oEntry is not null, and represents an application matching the specified family, this method retrieves the next application matching the specified family, otherwise it shall return null.
• If oEntry points to the last application matching the specified family, the method shall return null.

sFamily - the Application Family to look for (as defined in ISO 14443-3). This method shall filter registry entries based on an exact match with this parameter, with the following precisions:

• The information carried by the most significant byte (MSB) of this parameter is not defined, therefore the implementation may (but is not required to) ignore it, assuming a value of '00' for it.
• The Application Family is expected to be encoded by the least significant byte (LSB) of this parameter. Special rules defined in ISO 14443-3 regarding sub-family identifiers shall not be taken into account.

Returns:

the reference to the GPCLRegistryEntry interface object of the contactless applet matching the search criteria; null is returned if no application is matching or the end of the list is reached.

Throws:

javacard.framework.ISOException - with reason code

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if
  • the caller has not GLOBAL REGISTRY privilege, and
  • the caller has not CONTACTLESS ACTIVATION privilege, and
  • the caller is not a Security Domain or is a Security Domain but the oEntry is not directly associated with this Security Domain, and
  • the caller is not a CREL Application, or is a CRELApplication but the oEntry is not referencing this CREL Application.

java.lang.SecurityException - if oEntry is not a JCRE-owned instance of GPCLRegistryEntry.

javacard.framework.SystemException - with reason code SystemException.ILLEGAL_USE if the specified oEntry corresponds to an application that has been deleted.

See Also:

AFI_ANY, AFI_TRANSPORT, AFI_TELECOMMUNICATION, AFI_MULTIMEDIA, AFI_MEDICAL, AFI_IDENTIFICATION, AFI_GAMING, AFI_FINANCIAL, AFI_DATA_STORAGE

setVolatilePriority

public static void setVolatilePriority(GPCLRegistryEntry oEntry)

Sets up or resets the volatile priority for the specified entry.

An Application may be assigned the volatile priority only if it is already in the ACTIVATED state, or if it is in the DEACTIVATED state and can be activated. Moreover, a Member Application (part of an Application Group) cannot be assigned the volatile priority directly.

Any Application currently having the volatile priority (e.g. possibly a Member Application whose group has been assigned the volatile priority), the Application with the GPCLRegistryEntry.PRIVILEGE_CONTACTLESS_ACTIVATION privilege, and any CREL Application referenced by an Application currently having the volatile priority, may reset the volatile priority.

An Application (or Application Group) may be assigned the Volatile Priority even if the Volatile Priority is already assigned. In this case, the implementation shall first check that the Application can be activated and if so, the Volatile Priority shall be first reset before the Application gets the Volatile Priority. The behavior in the case the same Application already has and is assigned again the Volatile Priority remains implementation specific, in particular with respect to notifications.

When a request is made to assign the volatile priority, then

• the caller of this method shall have the GPCLRegistryEntry.PRIVILEGE_CONTACTLESS_ACTIVATION privilege, or
• the caller of this method shall be the Application corresponding to the specified entry and have the GPCLRegistryEntry.PRIVILEGE_CONTACTLESS_SELF_ACTIVATION privilege,
• otherwise:
  • The OPEN shall locate the CRS Application.
  • The OPEN shall call CRSApplication.processCLRequest(GPRegistryEntry, GPCLRegistryEntry, short) with the requester parameter set to the caller of this method, the target parameter set to oEntry, and the event parameter set to CLAppletEvent.EVENT_VOLATILE_SELECTION_PRIORITY_SET. This method is expected to check whether oEntry entry is allowed to acquire the volatile priority before requesting the CRS Application to perform the modification.
  • If CRS Application accepts the request, then it shall use setVolatilePriority(org.globalplatform.contactless.GPCLRegistryEntry) to assign the volatile priority to the Application.

If the volatile priority is assigned, then the CLAppletEvent.EVENT_VOLATILE_SELECTION_PRIORITY_SET shall be notified. In addition, an Application in the DEACTIVATED state that is assigned the volatile priority shall have its contactless activation state automatically transitioned to the ACTIVATED state: this latter modification shall NOT be notified.

If the volatile priority is reset, then the CLAppletEvent.EVENT_VOLATILE_SELECTION_PRIORITY_RESET shall be notified. In addition, any Application that previously had the volatile priority shall have its contactless activation state reset to its previous value (before being assigned the volatile priority): this latter modification shall NOT be notified.

The OPEN is responsible for notifying the change of volatile priority (if any) to the following Applications, except to the one that is at the origin of the request:

• the CRS Application if it implements the CRSApplication or CRELApplication interface,
• any CREL Application associated with oEntry, if that CREL Application implements the CRELApplication interface,
• the Application represented by oEntry, if it implements the CLApplet interface.

It shall be supported to assign or reset the volatile priority irrespective of the state of the contactless front end in the handset. When the contactless functionality is enabled the OPEN shall ensure that the contactless front end is provisioned so that it reflects the configuration of the contactless applets in the OPEN.

Parameters:

oEntry - The entry for which the volatile priority is requested. The null value shall be used to reset the volatile priority. If oEntry corresponds to a Head Application, then all corresponding Member Applications shall be assigned the volatile priority in the same order as in the GlobalPlatform registry.

Throws:

javacard.framework.ISOException - with reason code

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the caller does not have enough privileges, or the presence of the CRS Application is required and the CRS Application cannot be located or is not in a selectable state, or if the CRS Application rejects the request to get the volatile priority.
• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the Application corresponding to oEntry
  • is not in a selectable state, or
  • is in the NON ACTIVATABLE state, or
  • cannot be accessed through the contactless interface (see checkCommunicationInterfaceAccess(org.globalplatform.GPRegistryEntry, short)), or
  • corresponds to a Member Application
• ISO7816.SW_WRONG_DATA if the Application cannot be activated on the contactless interface because of conflicting RF parameters.
• ISO7816.SW_UNKNOWN if the call to the CRSApplication.processCLRequest(GPRegistryEntry, GPCLRegistryEntry, short) method resulted in an exception being thrown.

javacard.framework.SystemException - with reason code SystemException.ILLEGAL_USE if the specified oEntry corresponds to an Application that has been deleted.

java.lang.SecurityException - if oEntry is not a JCRE-owned instance of GPCLRegistryEntry.

getCardCLInfo

public static short getCardCLInfo(byte[] buffer,
                                  short offset,
                                  short info)

Retrieve the OPEN's conctactless parameters.

Parameters:

buffer - where requested information shall be written

offset - within buffer, where requested information shall be written

info - any CARD_INFO_XX constant.

Returns:

(offset + length of data written in buffer)

Throws:

ArrayIndexOutOfBoundsException - if storing the Application Information bytes would cause access outside array bounds or the offset is negative.

java.lang.NullPointerException - if buffer is null

setCommunicationInterface

public static void setCommunicationInterface(short sInterface,
                                             boolean onOff)

Switches ON or OFF persistently the specified communication interface at GlobalPlatform card level. The technical means for switching an interface ON and OFF are implementation dependent. When the contactless interface is switched off, a reset of the contactless interface shall be performed.

Parameters:

sInterface - GPCL_PROXIMITY_IO_INTERFACE

onOff - true to switch ON, false to switch OFF

Throws:

javacard.framework.ISOException - with reason code

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the caller has not GPCLRegistryEntry.PRIVILEGE_CONTACTLESS_ACTIVATION when managing the GPCL_PROXIMITY_IO_INTERFACE
• ISO7816.SW_WRONG_DATA if sInterface identifier is not defined.

checkCommunicationInterfaceAccess

public static boolean checkCommunicationInterfaceAccess(GPRegistryEntry entry,
                                                        short sInterface)

Checks whether a GPRegistryEntry can be accessed through specified communication interface.

Parameters:

sInterface - GPCL_PROXIMITY_IO_INTERFACE

Throws:

javacard.framework.ISOException - with reason code

• ISO7816.SW_WRONG_DATA if sInterface identifier is not defined.

Since:

export file version 1.1

getSecureElementType

public static byte getSecureElementType()

Gets the type of the Secure Element.

Possible values are:

• SECURE_ELEMENT_UNKNOWN
• SECURE_ELEMENT_UICC
• SECURE_ELEMENT_EMBEDDED
• SECURE_ELEMENT_SDCARD

Returns:

the secure element type

Since:

export file 1.2

getHostDeviceUserInterfaceState

public static short getHostDeviceUserInterfaceState()

Gets the current state of the host device user interface (UI).

NOTE: The mechanisms allowing this method to provide a reliable answer are not yet defined. Hence, the implementation is expected to return an approximate answer based on proprietary mechanisms. More precisions may be given in the future.

Returns:

A combination of none or several of the following constants (bit masks):

• HOST_DEVICE_UI_STATE_UNKNOWN: If this bit is set, the implementation is not able to provide any information about the state of the host device UI and all other bits shall be ignored.
• HOST_DEVICE_UI_AVAILABLE: If this bit is set, the UI shall be considered available, otherwise it shall be considered unavailable. As an approximation, the implementation may return an answer based on the power state of the Host Device.

Since:

export file 1.2

launchHostDeviceApplication

public static void launchHostDeviceApplication(byte[] parameters,
                                               short offset,
                                               short length)

Notifies the host device that it shall launch an application (on the host device) that is associated with the applet instance invoking this method.

This is a non-blocking method.

For an implementation based on the HCI specified in [ETSI TS 102 622], the AID of the applet instance invoking this method and the parameters passed to this method are typically used to create an event of type EVENT_TRANSACTION.

Parameters:

parameters - byte array containing the parameters transmitted to the host device application

offset - offset of the parameters

length - length of the parameters

Throws:

javacard.framework.ISOException - with reason code

• ISO7816.SW_FUNCTION_NOT_SUPPORTED if the card does not support host device notifications.
• ISO7816.SW_FILE_FULL if the card does not have enough resources to perform the notification.
• ISO7816.SW_WRONG_LENGTH if the length of the parameters is invalid (i.e. greater than 255).
• ISO7816.SW_CONDITIONS_NOT_SATISFIED if the conditions to call this method are not satisfied.

java.lang.NullPointerException - if parameters is null.

java.lang.ArrayIndexOutOfBoundsException - if operation would cause access of data outside array bounds.

java.lang.SecurityException - if parametersis not accessible in the caller's context e.g. parameters is not a global array nor an array belonging to the caller context.

Since:

export file 1.2